<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Strict//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<title>IupExpander</title>

<link rel="stylesheet" type="text/css" href="../../style.css">
<style type="text/css">
.style1 {
	font-size: large;
}
.style2 {
	color: #FF0000;
}
.style3 {
	background-color: #CEE7FF;
}
</style>
</head>
<body>
<div id="navigation">
  <ul>
    <li><a href="#Creation">Creation</a></li>
    <li><a href="#Attributes">Attributes</a></li>
    <li><a href="#Callbacks">Callbacks</a></li>
    <li><a href="#Notes">Notes</a></li>
    <li><a href="#Examples">Examples</a></li>
    <li><a href="#SeeAlso">See Also</a></li>
  </ul>
</div>

<h2>IupExpander <span class="style1">(since 3.8)</span></h2>
<p>Creates a void container that can interactively show or hide its child.</p>

  <p>
  It does not have a native representation, but it contains also several 
  elements to implement 
	the bar handler.</p>

<h3><a name="Creation">Creation</a></h3>

<pre>Ihandle* IupExpander(Ihandle*<strong> child</strong>); [in C]
iup.expander{<strong>child</strong>: ihandle} -&gt; (<strong>ih</strong>: ihandle) [in Lua]
expander(<strong>child</strong>) [in LED]</pre>
  <p><strong>child</strong>: Identifier of an interface element. It can be NULL 
  (nil in Lua), or empty in LED.</p>
  <p>
  <u>Returns:</u> the identifier of the 
  created element, or NULL if an error occurs.</p>

<h3><a name="Attributes">Attributes</a></h3>


<p><strong>AUTOSHOW</strong> (<font SIZE="3">non inheritable</font>): enables 
the automatic show of the child when mouse is over the handler for more than 1 
second. Default: No. See <a href="#Notes">Notes</a> bellow.</p>
<p><strong>ANIMATION</strong> (<font SIZE="3">non inheritable</font>): enable 
animation during open/close. Works only for BARPOSITION=TOP and does not works 
for AUTOSHOW. Also the child must be a native container like <strong>IupTabs</strong>, 
<strong>IupFrame</strong>, 
	<strong>IupBackgroundBox</strong>, or <strong>IupScrollBox,</strong> or it will not work accordantly. 
Values can be SLIDE (child controls slide down), CURTAIN (child controls appears 
as if a curtain is being pulled) or NO. Default: NO. ((since 3.14)</p>
<p class="info">The attribute <strong>NUMFRAMES</strong> can be used to control 
the number of frames used for the animation, the default value is 10 frames. The time between frames is 
controlled by the <strong>FRAMETIME</strong> attribute, the default value is 30ms (milliseconds). If the dialog has lots of controls and its layout computation 
takes longer than FRAMETIME, then a frame is lost, but the total animation time 
(numframes*frametime) is always the same.</p>


<p>
<strong>BACKCOLOR</strong> (<font SIZE="3">non inheritable</font>): background 
color of the bar handler. If not defined it will use the background color of the native parent. 
(since 3.9)</p>


<p><strong>BARPOSITION</strong> (creation only): indicates the bar handler 
position. 
Possible values are &quot;TOP&quot;, 
&quot;BOTTOM&quot;, &quot;LEFT&quot; or &quot;RIGHT&quot;. Default: &quot;TOP&quot;.</p>
<p><strong>BARSIZE</strong> (<font SIZE="3">non inheritable</font>): controls 
the size of the bar handler. Default: the height or width that fits all its 
internal elements according to BARPOSITION.</p>


<p><a href="../attrib/iup_expand.html">EXPAND</a> (<font SIZE="3">non inheritable</font>): 
the default value is &quot;YES&quot;.</p>
<p><strong>EXTRABUTTONS</strong> (<font SIZE="3">non inheritable</font>) 
(creation only): sets 
the number of extra image buttons at right when BARPOSITION=TOP. The maximum 
number of buttons is 3. See the EXTRABUTTON_CB callback. Default: 0. (since 
3.11)</p>
<p class="info"><strong>IMAGEEXTRAid</strong>: image name used for the button. 
id can be 1, 2 or 3. 1 is the rightmost button, and count from right to left.<br><strong>IMAGEEXTRAPRESSid</strong>: image name used 
for the button when pressed.<br>
<strong>IMAGEEXTRAHIGHLIGHTid</strong>: image name for the button used when mouse is over the 
button area.</p>


  <p><strong>FORECOLOR</strong> (<font SIZE="3">non inheritable</font>): title 
  text color. Default: the 
	global attribute DLGFGCOLOR. (since 3.9)</p>
<p><strong>OPENCOLOR</strong> (<font SIZE="3">non inheritable</font>): title 
text color when STATE=OPEN. Defaults to the FORECOLOR if not defined. (since 
3.14)</p>
<p><strong>HIGHCOLOR</strong> (<font SIZE="3">non inheritable</font>): title 
text color when highlighted. Works only when TITLEEXPAND=Yes. Defaults to the 
FORECOLOR if not defined. (since 3.14)</p>
<p>
<strong>FRAME</strong> (<font SIZE="3">non inheritable</font>): enables the frame line 
around the bar area. Default: No. (since 3.23)</p>
<p>
<strong>FRAMECOLOR</strong> (<font SIZE="3">non inheritable</font>): frame line color. Default: 
the global attribute DLGFGCOLOR. (since 3.23)</p>
<p>
<strong>FRAMEWIDTH</strong> (<font SIZE="3">non inheritable</font>): frame line width. Default: 
1. (since 3.23)</p>
<p><strong>IMAGE</strong> (<font SIZE="3">non inheritable</font>):
<span style="color: rgb(0, 0, 0); font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 20.799999237060547px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(255, 255, 255); display: inline !important; float: none;">
image name to </span>replace the arrow image by a custom image when STATE=CLOSE. Works only when 
BARPOSITION=TOP. Use <a href="../func/iupsethandle.html">IupSetHandle</a> or
	<a href="../func/iupsetattributehandle.html">IupSetAttributeHandle</a> to 
	associate an image to a name. See also <a href="iupimage.html">IupImage</a>. 
(since 3.11)</p>
<p class="info"><strong>IMAGEOPEN</strong>: image name used when STATE=OPEN.<br>
<strong>IMAGEHIGHLIGHT</strong>: image name used when mouse is over the bar 
handler and STATE=CLOSE.<br><strong>IMAGEOPENHIGHLIGHT</strong>: image name used 
when mouse is over the bar handler and STATE=OPEN.</p>
<p><strong>STATE</strong> (<font SIZE="3">non inheritable</font>): Show or hide 
the container elements. Possible values: &quot;OPEN&quot; (expanded) or &quot;CLOSE&quot; (collapsed). Default: 
OPEN. Setting this attribute will automatically change the layout of the entire 
dialog so the child can be recomposed.</p>
<p><strong>STATEREFRESH</strong> (<font SIZE="3">non inheritable</font>): when 
state is changed <strong>IupRefresh</strong> is automatically called. Can be Yes 
or No. Default: Yes. (since 3.16)</p>
<p><strong>TITLE</strong> (<font SIZE="3">non inheritable</font>): title text, 
shown in the bar handler near the expand/collapse button. When set it will reset 
TITLEIMAGE. Shown only when 
BARPOSITION=TOP.</p>

<p><strong>TITLEIMAGE</strong> (<font SIZE="3">non inheritable</font>): title 
image, 
shown in the bar handler near the expand/collapse button. When set it will reset 
TITLE (image and text title are mutually exclusive). Shown only when 
BARPOSITION=TOP. (since 3.14)</p>
<p class="info"><strong>TITLEIMAGEOPEN</strong>: image name used when STATE=OPEN.<br>
<strong>TITLEIMAGEHIGHLIGHT</strong>: image name used when mouse is over the 
title image and STATE=CLOSE.<br><strong>TITLEIMAGEOPENHIGHLIGHT</strong>: image name used 
when mouse is over the title image and STATE=OPEN.</p>
<p><strong>TITLEEXPAND</strong> (<font SIZE="3">non inheritable</font>): enable 
the expand/collapse action also at the tile. Default: NO. (since 3.14)</p>

  <p><b>WID</b> (read-only): returns -1 if mapped.</p>

  <blockquote>
    <hr>
</blockquote>

  <p>
<a href="../attrib/iup_font.html">FONT</a>,
    <a href="../attrib/iup_size.html">SIZE</a>,
<a href="../attrib/iup_rastersize.html">RASTERSIZE</a>,
<a href="../attrib/iup_clientsize.html">CLIENTSIZE</a>, 
	<a href="../attrib/iup_clientoffset.html">CLIENTOFFSET</a>, 
	<a href="../attrib/iup_position.html">POSITION</a>, 
<a href="../attrib/iup_minsize.html">
MINSIZE</a>, <a href="../attrib/iup_maxsize.html">
MAXSIZE</a>, <a href="../attrib/iup_theme.html">THEME</a>: 
also accepted.</p>


<h3><a name="Callbacks">Callbacks</a></h3>


<p><a href="../call/iup_action.html">ACTION</a>:
  Action generated after the expander state is interactively changed. (Since 3.9)</p>

  
    
<pre>int function(Ihandle*<strong> ih</strong>); [in C]<br><strong>ih</strong>:action() -&gt; (<strong>ret</strong>: number) [in Lua]</pre>

    
<p class="info"><strong>ih</strong>:
  identifier of the element that activated the 
  event.&nbsp;</p>

  
<p><strong>OPENCLOSE_CB</strong>:
  Action generated before the expander state is interactively changed. (Since 3.11)</p>

  
    
<pre>int function(Ihandle*<strong> ih</strong>, int <strong>state</strong>); [in C]<br><strong>ih</strong>:openclose<span class="style3">_</span>cb(<strong>state</strong>: number) -&gt; (<strong>ret</strong>: number) [in Lua]</pre>

    
<p class="info"><strong>ih</strong>:
  identifier of the element that activated the 
  event.&nbsp;<br><strong>state</strong>: new state to be applied. </p>
<p class="info"><strong>Returns</strong>: if return IUP_IGNORE the new state is 
ignored.</p>

  
<p><strong>EXTRABUTTON_CB</strong>:
  Action generated when any mouse button is 
  pressed or released. (since 3.11)</p>
<pre>int function(Ihandle* <strong>ih</strong>, int <strong>button</strong>, int <strong>pressed</strong>); [in C]
<strong>ih</strong>:extrabutton_cb(<strong>button</strong>, <strong>pressed</strong>: number) -&gt; (<strong>ret</strong>: number) [in Lua]</pre>
<blockquote>
<p><strong>ih</strong>:
  identifies the element that activated the 
  event.<br>
<strong>button</strong>: identifies the extra button. can be 1, 2 or 3. (this is 
not the same as BUTTON_CB)<br><strong>pressed</strong>:
  indicates the state of the button:</p>
	<p class="info">0 - mouse button was released;<br>
    1 - mouse button was pressed.</p>
</blockquote>
    
<h3><a name="Notes">Notes</a></h3>
<p>The bar handler elements are inside a <strong>IupBackgroundBox</strong> that is always the first child of the 
expander. It can be obtained using <strong>IupGetChild</strong> or <strong>
IupGetNextChild</strong>. Inside that box there is <strong>IupHbox</strong> or a
<strong>IupVbox</strong>, depending on BARPOSITION, that contains the 
interactive elements. All buttons are in fact <strong>IupLabel</strong> to avoid 
the <strong>IupButton</strong> margins and highlight effects. When 
BARPOSITION=TOP, the expand/collapse button is followed by a title label, then 
by a <strong>IupHbox</strong> containing the 3 or less extra buttons. (since 
3.14)</p>
<p>The container can be created with no elements and be dynamic filled using
  <a href="../func/iupappend.html">IupAppend</a> or
<a href="../func/iupinsert.html">IupInsert</a>.</p>
<p>When the TITLE is defined and BARPOSITION=TOP then the expand/collapse button 
is left aligned. In all other situations the expand/collapse button is centered.</p>
<p>When AUTOSHOW=Yes the dialog layout is NOT recalculated. The child is shown 
on top of the dialog, so the other children will not move or redraw. After the 
mouse is move away from the child then it is automatically hidden. 
<span class="style2"><strong>IMPORTANT</strong></span>: 
this feature will ONLY work if the child is a native container like <strong>
IupFrame</strong>, <strong>IupBackgroundBox, IupScrollBox</strong> or <strong>IupTabs</strong>.</p>


<h3><a name="Examples">Examples</a></h3>
<p><a href="../../examples/">Browse for Example Files</a></p>

<div align="center">
  <center>
  <table border="0" cellpadding="6" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
    <tr>
      <td><img border="0" src="images/iupexpander_open.png"><br>
		Container Expanded<br>(STATE = &quot;OPEN&quot;)</td>
      <td><img border="0" src="images/iupexpander_close.png"><br>
		Container Collapsed<br>(STATE = &quot;CLOSE&quot;)</td>
    </tr>
  </table>
  </center>
</div>

</body>

</html>
